{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  Using the API to run the emulation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We use a strongly defined HTTP API protocol to communicate with a C12 backend (get and receive the data). This tutorial will briefly present basic API calls that can be used for communication with the C12 backend. Our APIs are the low-level access to our emulator, and could be made compatible with other quantum computer frameworks and interfaces.\n",
    "\n",
    "To run each API, we need to pass the unique bearer token that will be used to verify the user's right to access C12's system.\n",
    "\n",
    "For communication with C12's system, it is possible to use the API library that encapsulates the HTTP communication with the C12 system using the Python request module.\n",
    "\n",
    "To start using it, we need to create an instance of the Request class, as shown in the following code snippet."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-10-08T14:48:58.047657Z",
     "start_time": "2024-10-08T14:48:56.390612Z"
    }
   },
   "outputs": [],
   "source": [
    "# Installing the c12simulator-clients package (for more details see jupyter 1)\n",
    "import os\n",
    "from c12_callisto_clients.api.client import Request\n",
    "\n",
    "TOKEN = os.getenv(\"C12_TOKEN\")\n",
    "\n",
    "# Create the request instance\n",
    "# Constructor of the Request class also accepts the verbose parameter, which can be use for more detailed output of the methods.\n",
    "\n",
    "request = Request(auth_token=TOKEN, verbose=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Run the simulation\n",
    "\n",
    "The method `start_job()` is used to start the simulation. It has the following arguments:\n",
    "- `qasm_str`: QASM string with quantum circuit\n",
    "- `shots`:  Number of trials for the simulation\n",
    "- `result`: what is desired output (statevector, counts, density_matrix)\n",
    "- `backend_name`: the name of the backend to run on"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-10-08T14:49:13.533602Z",
     "start_time": "2024-10-08T14:49:13.194631Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "('9815850c-26d1-41f7-bdf9-3a7a6ec4fc92', 'OPENQASM 2.0;\\ninclude \"qelib1.inc\";\\ngate iswap q0,q1 { s q0; s q1; h q0; cx q0,q1; cx q1,q0; h q1; }\\nqreg q[2];\\nry(-pi/2) q[1];\\niswap q[0],q[1];\\nrx(pi) q[0];\\nry(-pi/2) q[1];\\niswap q[0],q[1];\\nry(-pi/2) q[0];\\nrz(-pi/2) q[0];\\nrz(pi/2) q[1];\\nry(-pi/2) q[1];\\n')\n"
     ]
    }
   ],
   "source": [
    "from qiskit import QuantumCircuit\n",
    "from qiskit.qasm2 import dumps\n",
    "\n",
    "circuit = QuantumCircuit(2)\n",
    "circuit.h(0)\n",
    "circuit.cx(0, 1)\n",
    "\n",
    "\n",
    "qasm_str = dumps(circuit)\n",
    "res = request.start_job(\n",
    "    qasm_str=qasm_str, shots=100, result=\"density_matrix\", backend_name=\"c12sim-iswap\"\n",
    ")\n",
    "\n",
    "# The function returns the UUID and QasmStr of started job or HTTP error in case of problems\n",
    "print(res)\n",
    "job_uuid = res[0]\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Get the results of a simulation\n",
    "\n",
    "To get the emulation results, we can use the `get_job_result()` method that accepts one mandatory argument (job UUID string) and two optional ones.\n",
    "- `timeout`, which represents the number of seconds that the function will wait for job completion\n",
    "- `wait`, number of seconds between each check if the job is finished\n",
    "\n",
    "If we do not specify a timeout argument the function will run until the result is obtained"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-10-08T14:50:07.171443Z",
     "start_time": "2024-10-08T14:49:20.114429Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'status': 'FINISHED', 'results': {'density_matrix': [['(0.5003440602236676+0j)', '(-4.0683126779214476e-05+0.00019098408162360553j)', '(-4.0659775278663985e-05+0.00015270732715235404j)', '(0.49999981190306614-8.134297823249877e-05j)'], ['(-4.0683126779214476e-05-0.00019098408162360553j)', '(7.620763244616229e-08+0j)', '(6.15952858760575e-08+3.103381079950268e-09j)', '(-4.068618490670183e-05-0.0001908460661227806j)'], ['(-4.0659775278663985e-05-0.00015270732715235404j)', '(6.15952858760575e-08-3.103381079950268e-09j)', '(4.9911145303821645e-08+0j)', '(-4.0656626664155645e-05-0.00015259565074291268j)'], ['(0.49999981190306614+8.134297823249877e-05j)', '(-4.068618490670183e-05+0.0001908460661227806j)', '(-4.0656626664155645e-05+0.00015259565074291268j)', '(0.4996558136575547+0j)']]}, 'errors': ''}\n"
     ]
    }
   ],
   "source": [
    "job_result = request.get_job_result(job_uuid, timeout=120, wait=5)\n",
    "print(job_result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get the status of the job"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-10-08T14:50:12.344885Z",
     "start_time": "2024-10-08T14:50:12.164601Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "finished\n"
     ]
    }
   ],
   "source": [
    "status = request.get_job_status(job_uuid=job_uuid)\n",
    "print(status)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get all jobs\n",
    "\n",
    "Method `get_user_jobs()` can be used for obtaining information about all the jobs that have been run on the system for the user whose token is passed to the Request instance.\n",
    "\n",
    "The method has two arguments:\n",
    "- `limit`: an integer that represents the number of results to obtain\n",
    "- `offset`: an integer that represents the offset from the first result\n",
    "\n",
    "Using these two values, one can obtain the pagination, where the offset represents a page and limits the number of results per page. Method returns an array with results.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "number_of_results = 5  # Limit parameter, number of records to retrieve\n",
    "offset = 0\n",
    "count = 1\n",
    "while True:\n",
    "    jobs = request.get_user_jobs(limit=number_of_results, offset=offset)\n",
    "\n",
    "    for job in jobs:\n",
    "        print(f\"{count:}\")\n",
    "        print(job)\n",
    "        count += 1\n",
    "\n",
    "    if len(jobs) < number_of_results:\n",
    "        break\n",
    "\n",
    "    offset += number_of_results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get information about a specific job\n",
    "\n",
    "Using the method `get_job()` it is possible to retrieve the information about the specific job with a given UUID."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false,
    "ExecuteTime": {
     "end_time": "2024-10-08T14:51:00.666493Z",
     "start_time": "2024-10-08T14:51:00.371474Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'uuid': '9815850c-26d1-41f7-bdf9-3a7a6ec4fc92', 'time': '2024-10-08T14:49:13.520938', 'status': 'finished', 'options': {'shots': 100, 'result': 'density_matrix', 'basis': 'iswap'}, 'task': 'OPENQASM 2.0;\\ninclude \"qelib1.inc\";\\ngate iswap q0,q1 { s q0; s q1; h q0; cx q0,q1; cx q1,q0; h q1; }\\nqreg q[2];\\nry(-pi/2) q[1];\\niswap q[0],q[1];\\nrx(pi) q[0];\\nry(-pi/2) q[1];\\niswap q[0],q[1];\\nry(-pi/2) q[0];\\nrz(-pi/2) q[0];\\nrz(pi/2) q[1];\\nry(-pi/2) q[1];\\n', 'task_orig': 'OPENQASM 2.0;\\ninclude \"qelib1.inc\";\\nqreg q[2];\\nh q[0];\\ncx q[0],q[1];', 'errors': '', 'result': {'statevector': ['(-0.707350024308301+5.774697558332201e-05j)', '(5.7536886630460415e-05+0.0002699947020277173j)', '(5.749945628447106e-05+0.0002158818144976827j)', '(-0.7068633604703698-5.728953929746232e-05j)'], 'density_matrix': [['(0.5003440602236676+0j)', '(-4.0683126779214476e-05+0.00019098408162360553j)', '(-4.0659775278663985e-05+0.00015270732715235404j)', '(0.49999981190306614-8.134297823249877e-05j)'], ['(-4.0683126779214476e-05-0.00019098408162360553j)', '(7.620763244616229e-08+0j)', '(6.15952858760575e-08+3.103381079950268e-09j)', '(-4.068618490670183e-05-0.0001908460661227806j)'], ['(-4.0659775278663985e-05-0.00015270732715235404j)', '(6.15952858760575e-08-3.103381079950268e-09j)', '(4.9911145303821645e-08+0j)', '(-4.0656626664155645e-05-0.00015259565074291268j)'], ['(0.49999981190306614+8.134297823249877e-05j)', '(-4.068618490670183e-05+0.0001908460661227806j)', '(-4.0656626664155645e-05+0.00015259565074291268j)', '(0.4996558136575547+0j)']], 'counts': {'00': 57, '11': 43}, 'states': {'density_matrix': {}, 'statevector': {}}}}\n"
     ]
    }
   ],
   "source": [
    "job_data = request.get_job(job_uuid)\n",
    "print(job_data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "outputs": [],
   "source": [],
   "metadata": {
    "collapsed": false
   }
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}